/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.web.servlet;

import java.util.Enumeration;
import java.util.HashSet;
import java.util.Set;

import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import org.springframework.beans.BeanWrapper;
import org.springframework.beans.BeansException;
import org.springframework.beans.MutablePropertyValues;
import org.springframework.beans.PropertyAccessorFactory;
import org.springframework.beans.PropertyValue;
import org.springframework.beans.PropertyValues;
import org.springframework.context.EnvironmentAware;
import org.springframework.core.env.ConfigurableEnvironment;
import org.springframework.core.env.Environment;
import org.springframework.core.env.EnvironmentCapable;
import org.springframework.core.io.Resource;
import org.springframework.core.io.ResourceEditor;
import org.springframework.core.io.ResourceLoader;
import org.springframework.lang.Nullable;
import org.springframework.util.Assert;
import org.springframework.util.CollectionUtils;
import org.springframework.util.StringUtils;
import org.springframework.web.context.support.ServletContextResourceLoader;
import org.springframework.web.context.support.StandardServletEnvironment;

/**
 * 对HttpServlet的简单扩展，它将其配置参数(web.xml中servlet标记中的init-param条目)视为bean属性。
 *
 *
 *
 * 任何类型的servlet的一个方便的超类。配置参数的类型转换是自动的，使用转换后的值调用相应的setter方法。子类也可以指定所需的属性。
 * 没有匹配bean属性setter的参数将被忽略。 * 这个servlet将请求处理留给子类，继承HttpServlet的默认行为(doGet、doPost等)。
 *
 * 这个通用的servlet基类不依赖于Spring的org.springframework.context.ApplicationContext概念。
 * 简单的servlet通常不加载它们自己的上下文，而是从Spring根应用程序上下文访问服务bean，通过过滤器的ServletContext访问服务bean。
 * FrameworkServlet类是一个更特定的servlet基类，它加载自己的应用程序上下文。
 * FrameworkServlet作为Spring成熟的DispatcherServlet的直接基类
 *
 * Simple extension of {@link javax.servlet.http.HttpServlet} which treats
 * its config parameters ({@code init-param} entries within the
 * {@code servlet} tag in {@code web.xml}) as bean properties.
 *
 * <p>A handy superclass for any type of servlet. Type conversion of config
 * parameters is automatic, with the corresponding setter method getting
 * invoked with the converted value. It is also possible for subclasses to
 * specify required properties. Parameters without matching bean property
 * setter will simply be ignored.
 *
 * <p>This servlet leaves request handling to subclasses, inheriting the default
 * behavior of HttpServlet ({@code doGet}, {@code doPost}, etc).
 *
 * <p>This generic servlet base class has no dependency on the Spring
 * {@link org.springframework.context.ApplicationContext} concept. Simple
 * servlets usually don't load their own context but rather access service
 * beans from the Spring root application context, accessible via the
 * filter's {@link #getServletContext() ServletContext} (see
 * {@link org.springframework.web.context.support.WebApplicationContextUtils}).
 *
 * <p>The {@link FrameworkServlet} class is a more specific servlet base
 * class which loads its own application context. FrameworkServlet serves
 * as direct base class of Spring's full-fledged {@link DispatcherServlet}.
 *
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @see #addRequiredProperty
 * @see #initServletBean
 * @see #doGet
 * @see #doPost
 */
@SuppressWarnings("serial")
public abstract class HttpServletBean extends HttpServlet implements EnvironmentCapable, EnvironmentAware {

    /**
     * Logger available to subclasses.
     */
    protected final Log logger = LogFactory.getLog(getClass());

    @Nullable
    private ConfigurableEnvironment environment;

    /**
     * 必须配置的属性的集合，默认为空
     */
    private final Set<String> requiredProperties = new HashSet<>(4);


    /**
     * Subclasses can invoke this method to specify that this property
     * (which must match a JavaBean property they expose) is mandatory,
     * and must be supplied as a config parameter. This should be called
     * from the constructor of a subclass.
     * <p>This method is only relevant in case of traditional initialization
     * driven by a ServletConfig instance.
     *
     * @param property name of the required property
     */
    protected final void addRequiredProperty(String property) {
        this.requiredProperties.add(property);
    }

    /**
     * 实现了EnvironmentAware接口，自动注入Environment对象
     * <p>
     * Set the {@code Environment} that this servlet runs in.
     * <p>Any environment set here overrides the {@link StandardServletEnvironment}
     * provided by default.
     *
     * @throws IllegalArgumentException if environment is not assignable to
     *                                  {@code ConfigurableEnvironment}
     */
    @Override
    public void setEnvironment(Environment environment) {
        Assert.isInstanceOf(ConfigurableEnvironment.class, environment, "ConfigurableEnvironment required");
        this.environment = (ConfigurableEnvironment) environment;
    }

    /**
     * 实现了EnvironmentCapable接口，返回Environment对象
     * <p>
     * Return the {@link Environment} associated with this servlet.
     * <p>If none specified, a default environment will be initialized via
     * {@link #createEnvironment()}.
     */
    @Override
    public ConfigurableEnvironment getEnvironment() {
        if (this.environment == null) {
            this.environment = createEnvironment();
        }
        return this.environment;
    }

    /**
     * 创建Environment对象
     * <p>
     * Create and return a new {@link StandardServletEnvironment}.
     * <p>Subclasses may override this in order to configure the environment or
     * specialize the environment type returned.
     */
    protected ConfigurableEnvironment createEnvironment() {
        return new StandardServletEnvironment();
    }

    /**
     * 将配置参数映射到这个servlet的bean属性上，并调用子类初始化
     *
     * Map config parameters onto bean properties of this servlet, and
     * invoke subclass initialization.
     *
     * @throws ServletException if bean properties are invalid (or required
     *                          properties are missing), or if subclass initialization fails.
     */
    @Override
    public final void init() throws ServletException {

        // Set bean properties from init parameters.
        // 将servlet中配置的init-param参数封装到pvs变量中
        PropertyValues pvs = new ServletConfigPropertyValues(getServletConfig(), this.requiredProperties);
        if (!pvs.isEmpty()) {
            try {
                // 将当前的servlet对象转化成BeanWrapper对象，从而能够以spring的方法来将pvs注入到该beanWrapper中
                BeanWrapper bw = PropertyAccessorFactory.forBeanPropertyAccess(this);
                ResourceLoader resourceLoader = new ServletContextResourceLoader(getServletContext());
                // 注册自定义属性编辑器，一旦有Resource类型的属性，将会使用ResourceEditor进行解析
                bw.registerCustomEditor(Resource.class, new ResourceEditor(resourceLoader, getEnvironment()));
                // 模板方法，可以在子类调用，做一些初始化工作，bw代表的是DispatcherServlet
                initBeanWrapper(bw);
                // 以spring的方式来将pvs注入到该beanWrapper对象中,将配置的初始化值（contextConfigLocation）设置到DispatcherServlet
                bw.setPropertyValues(pvs, true);
            } catch (BeansException ex) {
                if (logger.isErrorEnabled()) {
                    logger.error("Failed to set bean properties on servlet '" + getServletName() + "'", ex);
                }
                throw ex;
            }
        }

        // Let subclasses do whatever initialization they like.
        // 模板方法，子类初始化的入口方法，查看FrameworkServlet#initServletBean方法
        initServletBean();
    }

    /**
     * Initialize the BeanWrapper for this HttpServletBean,
     * possibly with custom editors.
     * <p>This default implementation is empty.
     *
     * @param bw the BeanWrapper to initialize
     * @throws BeansException if thrown by BeanWrapper methods
     * @see org.springframework.beans.BeanWrapper#registerCustomEditor
     */
    protected void initBeanWrapper(BeanWrapper bw) throws BeansException {
    }

    /**
     * Subclasses may override this to perform custom initialization.
     * All bean properties of this servlet will have been set before this
     * method is invoked.
     * <p>This default implementation is empty.
     *
     * @throws ServletException if subclass initialization fails
     */
    protected void initServletBean() throws ServletException {
    }

    /**
     * Overridden method that simply returns {@code null} when no
     * ServletConfig set yet.
     *
     * @see #getServletConfig()
     */
    @Override
    @Nullable
    public String getServletName() {
        return (getServletConfig() != null ? getServletConfig().getServletName() : null);
    }


    /**
     * PropertyValues implementation created from ServletConfig init parameters.
     */
    private static class ServletConfigPropertyValues extends MutablePropertyValues {

        /**
         * Create new ServletConfigPropertyValues.
         *
         * @param config             the ServletConfig we'll use to take PropertyValues from
         * @param requiredProperties set of property names we need, where
         *                           we can't accept default values
         * @throws ServletException if any required properties are missing
         */
        public ServletConfigPropertyValues(ServletConfig config, Set<String> requiredProperties)
                throws ServletException {

            // 获取缺失的属性的集合
            Set<String> missingProps = (!CollectionUtils.isEmpty(requiredProperties) ?
                    new HashSet<>(requiredProperties) : null);

            // 遍历servletConfig的初始化参数集合，添加到servletConfigPropertyValues中，并从missingProps移除
            Enumeration<String> paramNames = config.getInitParameterNames();
            while (paramNames.hasMoreElements()) {
                String property = paramNames.nextElement();
                Object value = config.getInitParameter(property);
                // 添加到ServletConfigPropertyValues中
                addPropertyValue(new PropertyValue(property, value));
                // 从missingProps中移除
                if (missingProps != null) {
                    missingProps.remove(property);
                }
            }

            // Fail if we are still missing properties.
            if (!CollectionUtils.isEmpty(missingProps)) {
                throw new ServletException(
                        "Initialization from ServletConfig for servlet '" + config.getServletName() +
                                "' failed; the following required properties were missing: " +
                                StringUtils.collectionToDelimitedString(missingProps, ", "));
            }
        }
    }

}
